/* ----------------------------------------------------------------------------

	pax.cache.js Copyright (C) 2004, 2006, 2008 Mikkel Bergmann, Pointful

	Licence
	-------
	
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

	See lgpl.txt for licence details

---------------------------------------------------------------------------- */

/*
	Script: pax.cache
		This class caches objects in the DOM
		
	Author:
		Mikkel Bergmann, <http://www.pointful.com>

*/
/*
	TODO: 19-08-04 - We could in theory use the window name to store things in, as a session variable? Investigate this, as it would acrry between requests.
*/

var pax = pax || {};
pax.cache = pax.cache || {};

pax.cache.obj = {};						//	OBJ holder - key : obj
pax.cache.objExpire = {};				//	Expiry holder - key : [ entry time, expiry in seconds ]
pax.cache.defaultExpire = 600;			//	600 seconds = 10 minutes, as default expiry

/*	Method: pax.cache.isCached
	Returns true if an object is cached, (false otherwise), and expires and removes obj as required.
	
	Parameters:
		key - The key used when the object was cached.

	Returns:
		Boolean - true if object is cached, (false otherwise), and expires and removes obj as required.

	Example:
		(start code)
			<div id='pax.cache.isCached.example1'></div>
			[:.
				pax.cache.set( 'myObjKey', { box: 'Shoes' } );
				if( pax.cache.isCached( 'myObjKey' ) ) {
					var contents = "";
					for( var item in pax.cache.get('myObjKey') ) {
						contents += item + " with " + pax.cache.get('myObjKey')[item] + "\n";
					}
					pax.$('pax.cache.isCached.example1').innerHTML = "my object is a: " + contents;
				}
			:]
		(end)
		
		*isCached* returns true if anything has been cached under that key, and it has not expired.
		If it has expired, the object is removed from the cache, and false will be returned.

	Example:
		(start code)
			<div id='pax.cache.isCached.example2'></div>
			[:.
				var myFunc = function() {
					pax.$('pax.cache.isCached.example2').innerHTML = "This is from a cached function!";
				};
				pax.cache.set( 'myObjKey', myFunc );
				if( pax.cache.isCached( 'myObjKey' ) ) {
					pax.cache.get('myObjKey')();
				};
			:]
		(end)
		
		This example populates the DIV, using a cached function.
*/
pax.cache.isCached = function( key ) {
	for( var obj in pax.cache.obj ) {
		if( obj == key ) {
			var now = new Date();
			if( pax.cache.objExpire[key][1] != 0 ) {
				var expireTime = pax.cache.objExpire[key][0] + ( pax.cache.objExpire[key][1] * 1000 );
				if( expireTime < now.getTime() ) {
					pax.cache.remove( key );		// Destroy obj as it has expired.				
					return false;
				}
				else {
					return true;
				}
			}
			else return true;
		}
	}
	return false;
};

/*	Method: pax.cache.set
	Set an object in the cache.
	
	Parameters:
		key - The key to use for caching the object.
		value - The object or value to be cached.
		expire - Time in seconds for the value or object to be valid. Set to 0 to never expire the object (or omit expire)

	Example:
		(start code)
			[:_
				var myFruits = { 
					'apples': [
						'Granny Smith',
						'Red delicious'
					],
					'oranges': [
						'Valencia',
						'Blood'
					],
					'pears': 'green'
				};
				pax.cache.set( 'myObjKey', myFruits, 0 );
				var cacheObj = pax.util.toString( pax.cache.get('myObjKey') );
			:]
			The fruit object contains: [:= cacheObj :]
		(end)
		
		This will cache the myFruits object "forever".
*/
pax.cache.set = function( key, value, expire ) {

	//	Ensure we have a valid expiry time
	expire = (typeof expire != 'undefined')? expire : pax.cache.defaultExpire;
	
	var now = new Date();
	pax.cache.objExpire[key] = [ now.getTime(), expire ];
	pax.cache.obj[key] = value;
};

/*	Method: pax.cache.get
	Retreives an object from the cache, returns null if obj is not cached
	
	Parameters:
		key - The key to use for caching the object.

	Example:
		(start code)
			[:_
				var myFruits = { 
					'apples': [
						'Granny Smith',
						'Red delicious'
					],
					'oranges': [
						'Valencia',
						'Blood'
					],
					'pears': 'green'
				};
				pax.cache.set( 'myObjKey', myFruits, 0 );
				var myObj = pax.cache.get('myObjKey');
				var appleList = pax.util.toString( myObj.apples );
			:]
			The fruit object contains the following apples: [:= appleList :]
		(end)
		
		This will populate myFruits with object cached under 'myObjKey', or null if the key was not found.
*/
pax.cache.get = function( key ) {
	return ( pax.cache.isCached( key ) )? pax.cache.obj[key] : null;
};

/*	Method: pax.cache.remove
	Deletes an object from the cache, returns false if obj is not cached
	
	Parameters:
		key - The key to use for caching the object.

	Example:
		(start code)
			[:_
				var myFruits = { 
					'apples': [
						'Granny Smith',
						'Red delicious'
					],
					'oranges': [
						'Valencia',
						'Blood'
					],
					'pears': 'green'
				};
				pax.cache.set( 'myObjKey', myFruits, 0 );
				var objContents = pax.util.toString( pax.cache.get('myObjKey') );
			:]
			The fruit object contains the following: [:= objContents :]
			[:
				pax.cache.remove( 'myObjKey' );
				var objContents2 = pax.util.toString( pax.cache.get('myObjKey') );
			:]
			<hr>
			After removal, the fruit object contains the following: [:= objContents2 :]
		(end)
		
		This will remove the object cached under 'myObjKey', or run the error function otherwise.
*/
pax.cache.remove = function( key ) {
	for( var obj in pax.cache.obj ) {
		if( obj == key ) {
			delete pax.cache.obj[key];
			return true;
		}
	}
	return false;
};

